From 626fadf3f8212529f882cdd77a36eaa49b576580 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 28 Feb 2004 00:09:48 +0000 Subject: [PATCH] Include migrating-GtkComboBox.sgml. Sat Feb 28 01:11:53 2004 Matthias Clasen * gtk/gtk-docs.sgml: Include migrating-GtkComboBox.sgml. Sat Feb 28 01:11:34 2004 Matthias Clasen * gtk/Makefile.am (content_files): Add migrating-GtkComboBox.sgml. Fri Feb 27 22:54:01 2004 Matthias Clasen * gtk/gtk-docs.sgml: Sort deprecated widgets alphabetically. --- docs/reference/ChangeLog | 12 + docs/reference/gtk/Makefile.am | 4 +- docs/reference/gtk/gtk-docs.sgml | 12 +- docs/reference/gtk/migrating-GtkComboBox.sgml | 231 ++++++++++++++++++ 4 files changed, 253 insertions(+), 6 deletions(-) create mode 100644 docs/reference/gtk/migrating-GtkComboBox.sgml diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 11cfaff2be..b80f0f795f 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,15 @@ +Sat Feb 28 01:11:53 2004 Matthias Clasen + + * gtk/gtk-docs.sgml: Include migrating-GtkComboBox.sgml. + +Sat Feb 28 01:11:34 2004 Matthias Clasen + + * gtk/Makefile.am (content_files): Add migrating-GtkComboBox.sgml. + +Fri Feb 27 22:54:01 2004 Matthias Clasen + + * gtk/gtk-docs.sgml: Sort deprecated widgets alphabetically. + 2004-02-27 Federico Mena Quintero * gtk/migrating-GtkAction.sgml: Put explicit elements diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index dc96cf3ed1..315ef93fbd 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -44,10 +44,11 @@ IGNORE_HFILES= \ gtkintl.h \ gtkkeyhash.h \ gtkmarshal.h \ + gtkpathbar.h \ gtkprivate.h \ - gtktreeprivate.h \ gtkrbtree.h \ gtktreedatalist.h \ + gtktreeprivate.h \ gtktextbtree.h \ gtktextdisplay.h \ gtktextiterprivate.h \ @@ -93,6 +94,7 @@ content_files = \ framebuffer.sgml \ migrating-checklist.sgml \ migrating-GtkAction.sgml \ + migrating-GtkComboBox.sgml \ migrating-GtkFileChooser.sgml \ objects_grouped.sgml \ question_index.sgml \ diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 5c14e72d62..52566dbb99 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -182,6 +182,7 @@ + ]> @@ -514,17 +515,17 @@ that is, GUI components such as GtkButton or Deprecated - &GtkCombo; - &GtkOptionMenu; - &GtkItemFactory; &GtkCList; &GtkCTree; + &GtkCombo; + &GtkItemFactory; &GtkList; &GtkListItem; + &GtkOldEditable; + &GtkOptionMenu; &GtkPixmap; - &GtkProgress; &GtkPreview; - &GtkOldEditable; + &GtkProgress; &GtkText; &GtkTipsQuery; &GtkTree; @@ -547,6 +548,7 @@ that is, GUI components such as GtkButton or >k-Changes-2-0; >k-migrating-GtkFileChooser; >k-migrating-GtkAction; + >k-migrating-GtkComboBox; diff --git a/docs/reference/gtk/migrating-GtkComboBox.sgml b/docs/reference/gtk/migrating-GtkComboBox.sgml new file mode 100644 index 0000000000..ced0f8f507 --- /dev/null +++ b/docs/reference/gtk/migrating-GtkComboBox.sgml @@ -0,0 +1,231 @@ + + + + Matthias + Clasen + +
+ maclas@gmx.de +
+ + + + + Migrating from GtkOptionMenu and GtkCombo to GtkComboBox and GtkComboBoxEntry + + + Prior to 2.4, GTK+ offered two widgets for the task of selecting one + item from a list of options. + GtkOptionMenu presents the list of + options as a menu while GtkCombo presents + them in a Windows-style list popup. The only difference between the two + is that a GtkCombo allows to manually + edit the selected value, while the + GtkOptionMenu does not. + + + In GTK+ 2.4, a unified API for list selection was introduced, with + GtkComboBox for the non-editable case + and GtkComboBoxEntry for the + editable case. + The selection of the display style — menu or list — + is no longer done at the API level, but has been made themeable via + the style property + GtkComboBox::appearance. + + +
+ Migrating from GtkOptionMenu to GtkComboBox + + + Here is an example of a simple, but typical use of + GtkOptionMenu: + +GtkWidget *option_menu, *menu, *menu_item; + +option_menu = gtk_option_menu_new (); +menu = gtk_menu_new (); + +menu_item = gtk_menu_item_new_with_label ("First Item"); +gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item); +gtk_widget_show (menu_item); +menu_item = gtk_menu_item_new_with_label ("Second Item"); +gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item); +gtk_widget_show (menu_item); +menu_item = gtk_menu_item_new_with_label ("Third Item"); +gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item); +gtk_widget_show (menu_item); + +gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu); + + In order to react to the user's selection, connect to the "changed" + signal on the option menu and use gtk_option_menu_get_history() + to retrieve the index of the selected item. + + + And here is how it would be done with a + GtkComboBox: + +GtkWidget *combo_box; + +combo_box = gtk_combo_box_new_text (); + +gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "First Item"); +gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item"); +gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item"); + + In order to react to the user's selection, connect to the "changed" + signal on the combo box and use gtk_combo_box_get_active() + to retrieve the index of the selected item. + + + + A slightly more complex example involving images: + +GtkWidget *option_menu, *menu, *menu_item; + +option_menu = gtk_option_menu_new (); +menu = gtk_menu_new (); + +menu_item = gtk_image_menu_item_new_with_label ("First Item"); +gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf1)); +gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item); +gtk_widget_show (menu_item); +menu_item = gtk_image_menu_item_new_with_label ("Second Item"); +gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf2)); +gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item); +gtk_widget_show (menu_item); +menu_item = gtk_image_menu_item_new_with_label ("Third Item"); +gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf3)); +gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item); +gtk_widget_show (menu_item); + +gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu); + + + + can be done using a GtkComboBox + as follows: + +GtkListStore *store; +GtkTreeIter iter; +GtkCellRenderer *renderer; +GtkWidget *combo_box; + +store = gtk_list_store_new (2, GDK_TYPE_PIXBUF, G_TYPE_STRING); + +gtk_list_store_append (store, &iter); +gtk_list_store_set (store, &iter, 0, pixbuf1, 1, "First Item", -1); +gtk_list_store_append (store, &iter); +gtk_list_store_set (store, &iter, 0, pixbuf2, 1, "Second Item", -1); +gtk_list_store_append (store, &iter); +gtk_list_store_set (store, &iter, 0, pixbuf3, 1, "Third Item", -1); + +combo_box = gtk_combo_box_new_with_model (GTK_TREE_MODEL (store)); + +renderer = gtk_cell_renderer_pixbuf_new (); +gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (combo_box), renderer, FALSE); +gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo_box), renderer, + "pixbuf", 0, + NULL); + +renderer = gtk_cell_renderer_text_new (); +gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (combo_box), renderer, TRUE); +gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo_box), renderer, + "text", 1, + NULL); + + +
+ +
+ Migrating from GtkCombo to GtkComboBoxEntry + + + Here is an example of a simple, but typical use of a + GtkCombo: + +GtkWidget *combo; +GList *items = NULL; + +items = g_list_append (items, "First Item"); +items = g_list_append (items, "Second Item"); +items = g_list_append (items, "Third Item"); + +combo = gtk_combo_new (); +gtk_combo_set_popdown_strings (GTK_COMBO (combo), items); + + In order to react to the user's selection, connect to the "changed" + signal on the combo and use + gtk_entry_get_text (GTK_ENTRY (combo->entry)) + to retrieve the selected text. + + + And here is how it would be done using GtkComboBoxEntry: + +combo_box = gtk_combo_box_entry_new_text (); + +gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "First Item"); +gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item"); +gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item"); + + In order to react to the user's selection, connect to the "changed" + signal on the combo and use + gtk_entry_get_text (GTK_ENTRY (GTK_BIN (combo_box)->child)) + to retrieve the selected text. + +
+ +
+ New features + + + The new widgets have more to offer than a mere combination of the + features of GtkOptionMenu and + GtkCombo. Notable new features + include: + + + Grid mode + Sometimes it is preferable to display the available + options not in a linear list, but in a grid. A typical example + would be a "color combo" where the individual items are small + square color swatches. The new widgets support gridded display + with the functions + gtk_combo_box_set_wrap_width(), + gtk_combo_box_set_row_span_column() and + gtk_combo_box_set_column_span_column(). + + + + Display of icons + An often-heard complaint about + GtkOptionMenu is that the + icons which appear in the image menu items in its menu are not + displayed in the button showing the selected item. This limitation + has been removed in GtkComboBox; + the selected item appears in the same way as the options in + the popup. + + + + Full tree model power + + Since the new widgets are built around the same models that are + used for GtkTreeView, all of + the powerful machinery of tree models and cell renderers can be + used. + + + + +
+ + + + -- 2.30.2